home *** CD-ROM | disk | FTP | other *** search
/ Amiga Collections: Various / DevDisk 65 (1989)(DevWare PD).zip / DevDisk 65 (1989)(DevWare PD).adf / ifflib / IFFLib.doc < prev    next >
Text File  |  1990-07-11  |  22KB  |  678 lines
  1.  
  2.                  THE UNIVERSAL IFF LIBRARY FOR THE AMIGA
  3.  
  4.                         VERSION 18.5    12-MAR-90
  5.  
  6.  
  7.                 BY CHRISTIAN A. WEBER, ZURICH/SWITZERLAND
  8.  
  9.                                (BIX: chw)
  10.  
  11.  
  12. THIS PROGRAM IS IN THE PUBLIC DOMAIN. IT MAY BE FREELY DISTRUBUTED, COPIED
  13. AND USED FOR COMMERCIAL OR NON-COMMERCIAL PURPOSES.  IT MAY BE DISTRIBUTED
  14. WITH OR WITHOUT THIS DOCUMENTATION FILE.
  15.  
  16. TO MAINTAIN COMPATIBILITY,  YOU SHOULD NOT MAKE ANY CHANGES ON THE LIBRARY
  17. ITSELF. UPDATES WILL BE RELEASED BY THE AUTHOR.
  18.  
  19.  
  20.  
  21. WHAT IFF FILES CAN BE HANDLED?
  22. ------------------------------
  23.  
  24. I wrote this library to provide an easy way for reading and writing simple
  25. IFF files, such as pictures, animations, sound samples etc.
  26. In order to keep things easy, the IFF parser is NOT recursive. This means
  27. that it cannot handle files which contain recursive FORM or CAT definitions
  28. (e.g. a FORM containing another FORM).
  29. This restriction is not as important as you might think, since over 95%
  30. of all currently existing IFF files are not recursive.
  31. If you really need a recursive IFF parser, you should use the original
  32. Electronic Arts code, or the iffparse.library by Stuart Ferguson and
  33. Leo L. Schwab, which will be part of WB 1.4.
  34. Note that the iff.library can deal with ANIM files, although they contain
  35. nested FORMs. This is done with a little trick, see 'AnimExample.c' for
  36. details.
  37.  
  38.  
  39. CHANGES FOR V18.5
  40. -----------------
  41.  
  42. * OpenIFF() no longer trashes memory if a corrupt FORM (with some random
  43.   bytes at the end of file, as generated by old DPaint) is loaded.
  44.  
  45. * SHAM pictures (HAM with palette changes at each line) are now fully
  46.   supported by ShowIFF.
  47.  
  48.  
  49. CHANGES FOR V18.4
  50. -----------------
  51.  
  52. * The library now handles poorly written BODY chunks correctly (such as
  53.   written by old DPaint versions). It can now deal with pictures with
  54.   a height or depth of 0.
  55.  
  56.  
  57. CHANGES FOR V18.2
  58. -----------------
  59.  
  60. * The type IFFFILE has been redefined from 'CPTR' to 'void *'. This allows
  61.   you to use pointers to ULONG as your IFF file handles (which are easier
  62.   to use, see AnimExample.c), and the compiler won't generate warnings if
  63.   you pass these variables to the IFF library functions.
  64.  
  65. * FindChunk() can be called with a chunk ID of 0. It then returns a pointer
  66.   to the first byte after the end of the current FORM. This can be used
  67.   by ANIM readers for jumping from FORM to FORM (see example program).
  68.  
  69.  
  70. CHANGES FOR V18.1
  71. -----------------
  72.  
  73. * New function ModifyFrame(). This functions takes a bitmap and modifies
  74.   its planes according to a supplied DLTA chunk. This allows you to
  75.   easily display DPaint III and compatible animations.
  76.  
  77. * GetViewModes() now correctly masks out the forbidden bits (SPRITES,
  78.   VP_HIDE and genlock). This bug caused pictures with the VP_HIDE bit
  79.   set not to be displayed at all!
  80.   It is now safe to put the result of GetViewModes() directly to the
  81.   NewScreen.ViewModes field, as it was supposed to.
  82.   Note that GetViewModes() now returns the full 32 bit CAMG entry, so
  83.   the prototype for GetViewModes() has changed from UWORD to ULONG.
  84.   The upper 16 bits of the view modes are reserved for future use by CBM.
  85.  
  86. * GetColorTab() now correctly masks out the lower 4 bits of the color
  87.   bytes (These bits are used by some converted Sun rasterfiles).
  88.  
  89. * The DecodePic() decruncher is more robust, it does not write past the
  90.   end of the bitmap anymore (remember those nasty 81000007/9 gurus?)
  91.   If you have pictures which can't be displayed, PLEASE let me know!
  92.  
  93. * The library base format has changed. Since this structure was never
  94.   documented, this should not cause any compatibility problems. It is
  95.   very likely that this structure changes from release to release, so
  96.   don't use it!
  97.  
  98. * The name for IffError() in the Assembler include file has changed to
  99.   IFFError() (IFF in caps) to be compatible with the C names. This
  100.   requires a global search-and-replace operation on your asm source
  101.   files.
  102.  
  103. * The ShowIFF.c example program has been debugged. It should now handle
  104.   Overscan pictures correctly (in V16.4, it sometimes switched to
  105.   scrolling-mode if the picture was 480 rows high).
  106.   The file scanner is no longer recursive, it uses ARP's 'ALL' features.
  107.   ShowIFF now always returns the memory it allocates.
  108.  
  109. * There is a new example program 'AnimExample.c'. It loads and displays
  110.   a DPaint animation, the user can set the speed and number of loops.
  111.   This example shows how to use the new ModifyFrame() routine.
  112.  
  113.  
  114. CHANGES FOR V17.x
  115. -----------------
  116.  
  117. This version never existed (the IFFLIB17.ZOO release contained iff.lib 16.4).
  118. To avoid confusion, the new version number is now 18.
  119.  
  120.  
  121. CHANGES FOR V16.4
  122. -----------------
  123.  
  124. * The ShowIFF.c example program was completely rewritten. It now uses the
  125.   ARP library for command line parsing and directory searching. A powerful
  126.   WorkBench handler has been added which lets you display the pictures in
  127.   a drawer or an entire disk by selecting the drawer or disk icon and acti-
  128.   vating the ShowIFF icon with extended selection.
  129.   If a picture is larger than the screen, you can use the mouse to scroll
  130.   the screen. (I have some scanned pictures with a resolution of
  131.   2048x2048 pixels, which can be displayed with 1MB chip ram!)
  132.  
  133. * The Play8SVX demo has been added. It plays sampled sounds from CLI and
  134.   WorkBench.
  135.  
  136. * Internal changes to the library code (I now use the DevPac assembler V2
  137.   by HiSoft instead of the Manx 3.6  assembler)
  138.  
  139.  
  140. CHANGES FOR V16.3
  141. -----------------
  142.  
  143. * The BMHD property chunks can now be in any order (which worked for V16.1,
  144.   but was broken in 16.2).
  145.  
  146.  
  147. CHANGES FOR V16.2
  148. -----------------
  149.  
  150. * The SaveBitMap/SaveClip() routines sometimes generated a wrong CAMG chunk.
  151.   This is fixed now.
  152.  
  153. * There are no more decruncher overruns corrupting the memory list
  154.  
  155.  
  156. CHANGES FOR V16.1
  157. -----------------
  158.  
  159. Since V15.3 I got lots of suggestions, so I made the following changes.
  160. Note that this version is fully downward-compatible to V15.3.
  161.  
  162. * There was a bug in the DecodePic() routine which called the guru if the
  163.   width of the picture was not a multiple of 16. It's fixed now.
  164.  
  165. * The GetViewModes() routines now calculates the viewmodes correctly for
  166.   all picture sizes, including Super-Overscan (produced by DigiView 3.0).
  167.  
  168. * When you open an IFF file with the OpenIFF() call, memory is allocated
  169.   and the file is read into that memory. Normally, all files are loaded
  170.   into whatever memory is available, but '8SVX' files are always loaded to
  171.   CHIP memory (the memory which is accessable by the Amiga's custom chips).
  172.   This solution is good for playing IFF sounds, but it is not satisfactory
  173.   for some other applications. The solution of this problem is quite easy:
  174.   I added a new routine called 'NewOpenIFF', which allows you to specify
  175.   the type of memory for the file.
  176.   So if you want to load an IFF instrument into any RAM, the right command
  177.   is: 'f=NewOpenIFF(filename,0L)' or 'f=OpenIFF(filename,MEMF_PUBLIC)'.
  178.   You can use any memory attributes you want (PUBLIC,CHIP,FAST...).
  179.  
  180. * The file 'iff.h' is now split into two files: 'iff.h', which contains the
  181.   structure definitions and function declarations, and 'IffGlue.asm',
  182.   which contains the C to Assembler interface routines. These routines are
  183.   needed for the Manx C compilere V3.6.
  184.  
  185. * The file 'IFFPragmas.h" is added to support the Lattice C compiler. It
  186.   was taken from an usenet article by Lyle E. Levine. (Thanks!)
  187.  
  188. * The demo file 'ShowIFF.c' now correctly handles overscan pictures.
  189.  
  190.  
  191.  
  192. LIBRARY FUNCTION OVERVIEW
  193. -------------------------
  194.  
  195. Name        Offset    Description
  196.  
  197. OpenIFF        -30    Allocate memory for an IFF-file and load it
  198. CloseIFF    -36    Finish access to an IFF-file and deallocate memory
  199. FindChunk    -42    Find a specific chunk in an IFF file
  200. GetBMHD        -48    Find the BitMapHeader of an ILBM file
  201. GetColorTab     -54    Find CMAP chunk, convert it to an Amiga ColorTable
  202. DecodePic    -60    Decode the BODY of an ILBM file into a BitMap
  203. SaveBitMap    -66    Save the contents of a BitMap as an IFF-file
  204. SaveClip    -72    Save a part of a BitMap as an IFF-file
  205. IFFError    -78    Get detailed error descrpition if a routine fails
  206. GetViewModes     -84    Get the Amiga-specific ViewModes
  207. NewOpenIFF    -90    Allocate specific memory for an IFF-file and load it
  208. ModifyFrame    -96    Modify an anim frame using a DLTA chunk
  209. (to be continued)
  210.  
  211.  
  212.  
  213. DETAILED DESCRIPTION OF THE LIBRARY FUNCTIONS
  214. ---------------------------------------------
  215.  
  216. (This documentation was translated from German to English in half an hour,
  217. so please be tolerant!)
  218.  
  219. IFF/NewOpenIFF                                                 IFF/NewOpenIFF
  220.  
  221.    NAME
  222.     NewOpenIFF -- allocate memory for an IFF-file and read it
  223.  
  224.    SYNOPSIS
  225.     ifffile = NewOpenIFF(filename,memattr)
  226.      D0                   A0       D0
  227.  
  228.    LIBRARY OFFSET
  229.         -90
  230.  
  231.    FUNCTION
  232.     This function opens a file on a disk and looks whether it's an IFF
  233.     file or not. If it is an IFF file, memory is allocated and the file
  234.     is read into memory. The 'memattr' argument is taken to define the
  235.     memory type. Normally memattr is set to 0 or MEMF_PUBLIC.
  236.     If an error occurs, 0 is returned, and you can call IFFError() to
  237.     get the error number.
  238.  
  239.    INPUTS
  240.     filename - Pointer to a null-terminated string
  241.     memattr  - Memory requirements as used for Exec's AllocMem(),
  242.                such as MEMF_CHIP, MEMF_PUBLIC ...
  243.                (MEMF_CLEAR is not necessary)
  244.  
  245.    RESULT
  246.     ifffile - 'FileHandle', points to the beginning of the IFF file
  247.     ("FORM...."), Zero if unsuccessful. Call IFFError() to get the
  248.     reason of the failure.
  249.  
  250.    SEE ALSO
  251.     OpenIFF, CloseIFF, IFFError
  252.  
  253.    BUGS
  254.     None known
  255.  
  256.  
  257. IFF/OpenIFF                                                       IFF/OpenIFF
  258.  
  259.    NAME
  260.     OpenIFF -- allocate memory for an IFF-file and read it
  261.  
  262.    SYNOPSIS
  263.     ifffile = OpenIFF(filename)
  264.      D0                A0
  265.  
  266.    LIBRARY OFFSET
  267.         -90
  268.  
  269.    FUNCTION
  270.     This function does the same as the NewOpenIFF() routine above,
  271.     except that you cannot specify the type of memory which is
  272.     allocated for the file. Normally the type is 0 which means 'any
  273.     memory', but if the IFF file type is '8SVX', the file is ALWAYS
  274.     loaded into CHIP memory. If you wish to override these defaults,
  275.     use NewOpenIFF() instead of OpenIFF().
  276.  
  277.    INPUTS
  278.     filename - Pointer to a null-terminated string
  279.  
  280.    RESULT
  281.     ifffile - 'FileHandle', points to the beginning of the IFF file
  282.     ("FORM...."), 0 if unsuccessful. Call IFFError() to get the
  283.     reason of the failure.
  284.  
  285.    SEE ALSO
  286.     NewOpenIFF, CloseIFF, IFFError
  287.  
  288.    BUGS
  289.     None
  290.  
  291.  
  292. IFF/CloseIFF                                                     IFF/CloseIFF
  293.  
  294.    NAME
  295.     CloseIFF -- finish access to an IFF-file and deallocate memory
  296.  
  297.    SYNOPSIS
  298.     CloseIFF(ifffile)
  299.               A1
  300.  
  301.    LIBRARY OFFSET
  302.         -36
  303.  
  304.    FUNCTION
  305.     Returns the memory previously allocated by OpenIFF().
  306.  
  307.    INPUTS
  308.     ifffile - IFF file pointer, from OpenIFF()
  309.  
  310.    RESULT
  311.     none
  312.  
  313.    SEE ALSO
  314.     OpenIFF
  315.  
  316.    BUGS
  317.     If A1 contains garbage, an 81000005 Guru will visit you...
  318.  
  319.  
  320. IFF/FindChunk                                                   IFF/FindChunk
  321.  
  322.    NAME
  323.     FindChunk -- find an IFF-chunk
  324.  
  325.    SYNOPSIS
  326.     chunk = FindChunk(ifffile,chunkname)
  327.      D0               A1       D0
  328.  
  329.    LIBRARY OFFSET
  330.         -42
  331.  
  332.    FUNCTION
  333.     Find a specific chunk in an IFF file
  334.  
  335.    INPUTS
  336.     ifffile - pointer to a FORM, normally the result of OpenIFF()
  337.     chunkname - 4 characters packed ASCII ('BODY', 'VHDR' ...)
  338.                 if chunkname is 0, FindChunk() returns a pointer to the
  339.                 first byte after the end of the current FORM. This can
  340.                 be used byANIM readers for jumping from FORM to FORM.
  341.  
  342.    RESULT
  343.     Pointer to the beginning of the chunk (that means to the chunk
  344.     name itself, followed by the chunk size), zero if chunk not found
  345.  
  346.    SEE ALSO
  347.     GetBMHD, GetColorTab
  348.  
  349.    BUGS
  350.     none
  351.  
  352.  
  353. IFF/GetBMHD                                                       IFF/GetBMHD
  354.  
  355.    NAME
  356.     GetBMHD -- find a BitMapHeader of an IFF-file
  357.  
  358.    SYNOPSIS
  359.     header = GetBMHD(ifffile)
  360.      D0              A1
  361.  
  362.    LIBRARY OFFSET
  363.         -48
  364.  
  365.    FUNCTION
  366.     Returns a pointer to a 'BitMapHeader' structure as defined in
  367.     iff.h and iff.i
  368.  
  369.    INPUTS
  370.     ifffile - IFF file pointer, returned by OpenIFF()
  371.  
  372.    RESULT
  373.     Pointer to the BitMapHeader, or 0 if no BMHD chunk found
  374.  
  375.    SEE ALSO
  376.     FindChunk, GetColorTab
  377.  
  378.    BUGS
  379.     none
  380.  
  381.  
  382. IFF/GetColorTab                                               IFF/GetColorTab
  383.  
  384.    NAME
  385.     GetColorTab -- find a CMAP chunk and convert it to a ColorTable
  386.  
  387.    SYNOPSIS
  388.     count = GetColorTab(ifffile,colortable)
  389.      D0                  A1      A0
  390.  
  391.    LIBRARY OFFSET
  392.         -54
  393.  
  394.    FUNCTION
  395.     Searches the CMAP chunk of an IFF file and converts it, if it's
  396.     there, to an Amiga color table structure. This colortable can
  397.     directly be used as a parameter for the LoadRGB4() function.
  398.  
  399.    INPUTS
  400.     ifffile - IFF file pointer, returned by OpenIFF()
  401.     colortable - Pointer to a block of memory which must be large
  402.                  enough to hold the colortable (2 bytes per color)
  403.  
  404.    RESULT
  405.     Number of colors actually found, or zero if the file has no
  406.     CMAP chunk
  407.  
  408.    SEE ALSO
  409.     FindChunk, GetBMHD
  410.  
  411.    WARNING
  412.     the colortable must be WORD aligned
  413.  
  414.  
  415. IFF/DecodePic                                                   IFF/DecodePic
  416.  
  417.    NAME
  418.     DecodePic -- decode the BODY of an ILBM file into a BitMap
  419.  
  420.    SYNOPSIS
  421.     success = DecodePic(ifffile,bitmap)
  422.      D0                 A1      A0
  423.  
  424.    LIBRARY OFFSET
  425.         -60
  426.  
  427.    FUNCTION
  428.     Decodes and decrunches a picture into the BitMap you supplied.
  429.     If the picture is larger than your BitMap's planes, it will be
  430.     truncated. If your BitMap is larger than the picture, the picture
  431.     will be drawn into the top left corner of your BitMap.
  432.     If the picture has more planes (colors) than your BitMap, the
  433.     operation will fail and 0 will be returned.
  434.  
  435.    INPUTS
  436.     ifffile - IFF file pointer, from OpenIFF()
  437.     bitmap  - Pointer to a properly initialized BitMap structure:
  438.           bm_Planes[] must point to valid BitPlanes,
  439.           bm_Depth contains the number of planes.
  440.           bm_Width and bm_Height must be set according to the
  441.           size of your bit planes.
  442.  
  443.    RESULT
  444.     Non-zero if  OK, 0 if error, Call IFFError() to know the reason
  445.     of the failure
  446.  
  447.    WARNING
  448.     This routine needs at least 520 bytes of stack
  449.  
  450.    BUGS
  451.     The width of the IFF picture (in pixels) must be a multiple of 8
  452.     (I've never seen a picture which didn't obey this rule!)
  453.  
  454.  
  455. IFF/SaveBitMap                                                 IFF/SaveBitMap
  456.  
  457.    NAME
  458.     SaveBitMap -- save the planes of a BitMap as an IFF-file
  459.  
  460.    SYNOPSIS
  461.     result = SaveBitMap(filename,bitmap,colortable,flags)
  462.      D0                  A0       A1     A2         D0
  463.  
  464.    LIBRARY OFFSET
  465.         -66
  466.  
  467.    FUNCTION
  468.     Save the planes of a BitMap as an IFF-file, optionally with a
  469.     colortable. The IFF file will contain the following chunks:
  470.  
  471.     FORM  -  The IFF header, with the type ILBM
  472.     BMHD  -  The BitMap Header structre
  473.     CMAP  -  The color map, this chunk is omitted if colortable is zero
  474.     CAMG  -  The Amiga ViewModes word, contains the special ViewModes
  475.              information (HAM, LACE, HIRES ...)
  476.     BODY  -  The (crunched or uncompressed) picture
  477.  
  478.    INPUTS
  479.     filename    - Name of the IFF file to create
  480.     bitmap      - Pointer to the BitMap holding your picture
  481.     colortable  - Pointer to an Amiga ColorTable structure or zero
  482.                   (if colortable = 0, no CMAP chunk will be generated).
  483.     flags       - Bit 0: 1 = Use the "CmpByteRun1" compression algorythm,
  484.                          0 = Save the file uncompressed
  485.                       Bit 7: 1 = This is a HAM (Hold and modify) picture
  486.                          0 = This is a normal or Extra-Halfbrite picture
  487.  
  488.    RESULT
  489.     Non-zero if successful, 0 if error, Call IFFError() to know the
  490.     reason of the failure
  491.  
  492.    SEE ALSO
  493.     SaveClip
  494.  
  495.  
  496. IFF/SaveClip                                                     IFF/SaveClip
  497.  
  498.    NAME
  499.     SaveClip -- save a part of a BitMap as an IFF-file
  500.  
  501.    SYNOPSIS
  502.     result = SaveClip(filename,bitmap,coltab,flags,xoff,yoff,width,height)
  503.      D0                A0       A1     A2     D0    D1   D2   D3    D4
  504.  
  505.    LIBRARY OFFSET
  506.         -72
  507.  
  508.    FUNCTION
  509.     Save a part of a BitMap as an IFF file
  510.  
  511.    INPUTS
  512.     filename    - Name of the IFF file to create
  513.     bitmap      - Pointer to the BitMap holding your picture
  514.     colortable  - Pointer to an Amiga ColorTable structure or zero
  515.                   (if colortable = 0, no CMAP chunk will be generated).
  516.     flags       - Bit 0: 1 = Use the "CmpByteRun1" compression algorythm,
  517.                          0 = Save the file uncompressed
  518.                       Bit 7: 1 = This is a HAM (Hold and modify) picture
  519.                          0 = This is a normal or Extra-Halfbrite picture
  520.     xoff        - X offset of the clip to be saved (bytes from the left)
  521.     yoff        - Y offset of the clip to be saved (lines from the top)
  522.     width       - width in bytes of the rectangle
  523.     height      - height in lines of the rectangle
  524.  
  525.    RESULT
  526.     Non-zero if successful, 0 if error, Call IFFError() to know the
  527.     reason of the failure
  528.  
  529.    SEE ALSO
  530.     SaveBitMap
  531.  
  532.    BUGS
  533.     The width of the rectangle will be rounded to WORD boundaries,
  534.     because DPAINT wants it!
  535.  
  536.  
  537. IFF/IFFError                                                     IFF/IFFError
  538.  
  539.    NAME
  540.     IFFError -- Get detailed error descrpition
  541.  
  542.    SYNOPSIS
  543.     error = IFFError()
  544.     D0
  545.  
  546.    LIBRARY OFFSET
  547.         -78
  548.  
  549.    FUNCTION
  550.     If one of the above functions returns zero, you can call IFFError()
  551.     to know the reason for the failure. An error code is returned,
  552.     please refer to the files 'iff.h' or 'iff.i' for the complete
  553.     list of errors.
  554.  
  555.    INPUTS
  556.     none
  557.  
  558.    RESULT
  559.     Error-number generated by the latest function call, or zero if
  560.     no error
  561.  
  562.     Cuurently the following numbers are used:
  563.  
  564.     Nr.  Symbol             Function     Description
  565.  
  566.     16   IFF_CANTOPENFILE   OpenIFF()     File not found
  567.     17   IFF_READERROR      OpenIFF()     Read() returned an error
  568.     18   IFF_NOMEM          OpenIFF()     Not enough memory for the file
  569.     19   IFF_NOTIFF         OpenIFF()     File is not IFF
  570.     20   IFF_WRITEERROR    SaveBitMap()  Cannot write the file
  571.  
  572.     24   IFF_NOILBM         DecodePic()   IFF file is not an ILBM file
  573.     25   IFF_NOBMHD         DecodePic()   BMHD chunk not found
  574.     26   IFF_NOBODY         DecodePic()   BODY chunk not found
  575.     27   IFF_TOOMANYPLANES  DecodePic()   Picture has more planes than
  576.                                           your BitMap
  577.     28   IFF_UNKNOWNCOMPRESSION  "        Unknown compression type
  578.     29   IFF_NOANHD         ModifyFrame() ANHD chunk not found
  579.     30   IFF_NODLTA         ModifyFrame() DLTA chunk not found
  580.  
  581.     -1   IFF_BADTASK        A task which did not open the IFF library
  582.                             tried to call IFFError(). Since the IFF
  583.                             library is capable of multi-tasking, the
  584.                             error-values are stored for each task
  585.                             separately.
  586.  
  587.    SEE ALSO
  588.  
  589.    BUGS
  590.     If you don't close the IFF library at the end of your program
  591.     (using CloseLibrary()) the error node will not be freed. The
  592.     same task will then not be able to re-open the iff.library!!!
  593.     (This is not a bug, it's a feature!)
  594.  
  595.  
  596. IFF/GetViewModes                                             IFF/GetViewModes
  597.  
  598.    NAME
  599.     GetViewModes -- Get Amiga-specific ViewModes
  600.  
  601.    SYNOPSIS
  602.     viewmodes = GetViewModes(ifffile)
  603.     D0                        A1
  604.  
  605.    LIBRARY OFFSET
  606.         -84
  607.  
  608.    FUNCTION
  609.     Searches the IFF file for a 'CAMG' chunk which holds the view modes
  610.     information. If there is no CAMG chunk, the view modes are calcu-
  611.     lated using the information in the BitMapHeader structure.
  612.     You can directly put the low WORD of the result of a GetViewModes()
  613.     call into the ns_ViewModes field of a NewScreen structure. All
  614.     forbidden bits are masked out.
  615.  
  616.    INPUTS
  617.     ifffile - IFF file pointer, returned from OpenIFF()
  618.  
  619.    RESULT
  620.     viewmodes - LONG containing the view modes (HAM, LACE, HIRES ...)
  621.     Under Kickstart V1.3, only the lower WORD is used.
  622.  
  623.    SEE ALSO
  624.  
  625.    BUGS
  626.     If the IFF file has no CAMG chunk and 6 bitplanes, the HAM bit
  627.     will be set. This is not always correct since the picture could
  628.     be in the Extra Halfbrite mode. You can load such Halfbrite
  629.     pictures into DPaint III and save them again, DPaint will generate
  630.     the correct CAMG chunk.
  631.  
  632. IFF/ModifyFrame                                               IFF/ModifyFrame
  633.  
  634.    NAME
  635.     ModifyFrame -- Modify an anim frame using a DLTA chunk
  636.  
  637.    SYNOPSIS
  638.     success = ModifyFrame(modifyform,bitmap)
  639.      D0                   A1         A0
  640.  
  641.    LIBRARY OFFSET
  642.         -96
  643.  
  644.    FUNCTION
  645.     Uses the DLTA chunk of the supplied FORM to modify the planes-data
  646.     of the bitmap. Usually, playback of ANIMs will require two buffers,
  647.     and double-buffering between them. So the data in the bitmap must
  648.     be two frames back, and the DLTA chunk is used to modify the hidden
  649.     frame to the next frame to be shown.
  650.  
  651.    INPUTS
  652.     modifyform - pointer to the FORM containing the actual DLTA chunk
  653.     bitmap  - Pointer to a properly initialized BitMap structure,
  654.           the planes must contain the image which was displayed
  655.           to frames back (using double-buffering)
  656.  
  657.    RESULT
  658.     Non-zero if  OK, 0 if error; call IFFError() to know the reason
  659.     of the failure
  660.  
  661.    WARNINGS
  662.     This routine needs at least 820 bytes of stack
  663.  
  664.    RESTRICTIONS
  665.     Currently, only compression type 5 (Byte Vertical Delta Mode) is
  666.     implemented. If you have animations which use modes 1 to 4, try
  667.     loading them with DPaint III and saving them again.
  668.     Sculpt-Animate pictures do not work, because I have no documentation
  669.     about the compression scheme they use.
  670.     I will implement some more compression types upon request.
  671.  
  672.    BUGS
  673.     The size of the bitmap is not checked by this routine, the planes
  674.     must have at least the size described in the BMHD of the anim
  675.     file.
  676.  
  677.  
  678.